home *** CD-ROM | disk | FTP | other *** search
/ World of Amiga / World of Amiga.iso / archive / assemblers / ira102.lha / ira / ira.doc < prev    next >
Text File  |  1993-09-06  |  13KB  |  326 lines
  1.  
  2.  
  3.  
  4.  
  5.                      ________________
  6.                     /   /         /  \
  7.                    /   /  ____   /    \
  8.                   /   /  /   /  /  /\  \
  9.                  /   /  /   /  /  /  \  \
  10.                  \   \  \  /  /  /    \  \
  11.                   \   \  \/  /   \/\/\/   \
  12.                    \   \     \             \
  13.                     \   \     \    /\/\/\   \
  14.                     /   /  /\  \   \     \   \
  15.                    /   /  /  \  \   \     \   \
  16.                   /   /  /    \  \   \     \   \
  17.                   ¯¯¯¯¯¯¯      ¯¯¯¯¯¯¯      ¯¯¯¯
  18.  
  19.  
  20.  
  21.                       IRA  V1.02  9/93
  22.  
  23.                     Shareware reassembler
  24.  
  25.                     (C) 1993 Tim Ruehsen
  26.  
  27.                   SHAREWARE 15US$/20DM CASH
  28.  
  29.  
  30.  
  31. FORWORD
  32. ¯¯¯¯¯¯¯
  33. Sorry, this is not the final doc-file and this is not the final IRA !!!
  34. I was in a hurry, when I wrote this doc. Next one is better.
  35. The future will bring you 6888x (FPU) and MMU commands, perhaps the IRA
  36. will get interactive. That depends on your comments and letters.
  37. If you find any errors, send me a disk with the program that causes trouble
  38. and tell me what command line you used. The disk will be returned with the
  39. newest version of IRA and some PD stuff.
  40.  
  41.  
  42. DESCRIPTION
  43. ¯¯¯¯¯¯¯¯¯¯¯
  44. IRA102 is version V1.02 of my reassembler IRA (Where the 'I' comes from shows
  45. the future). Reassembler means that IRA translates any executable or binary
  46. file into an assembler sourcecode that might immediately be translated back by
  47. an assembler. E.g., you can do that with a debugging option. After that you
  48. can examine that program with any debugger. That's fine for finding and 
  49. analysing viruses, repairing old programs, even optimising alien programs.
  50.  
  51. When translating back with an assembler, switch optimising off,except you know
  52. exactly what you're doing !!!
  53.  
  54. IRA is for use from CLI/SHELL.
  55.  
  56. IRA has some command line options. Just type 'ira' to get a short description.
  57.  
  58. This version works fine with the MC68000 and the MC68010 processor.
  59. FPU and MMU commands are not implemented yet.
  60. Reassembling programs for 68020+ processors may cause trouble with some
  61. addressing modes.
  62. For example: (0,A0) and (0,A0) seems to be the same, but the first may be
  63. (d16,An) and the second (bd,An,Xn) with Xn suppressed (and bd might be 16
  64. or 32 bit). There are other ambiguous addressing modes.
  65.  
  66.  
  67. DESCRIPTION OF THE COMMAND-LINE OPTIONS
  68. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  69. The default values are in brackets.
  70.  
  71. -M680x0 (-M68000)
  72.         This specifies the type of processor for which the program should
  73.         be reassembled. This doesn't has anything to do with the machine
  74.         you're running IRA on. Most programs are written for 68000 CPUs.
  75.         If anything other than -M68000 is specified a MACHINE statement
  76.         in the .ASM file is created. This works fine with the PhxAss
  77.         assembler (see below). For any other assembler this statement
  78.         possibly has to be changed.
  79.  
  80. -BINARY (off)
  81.         IRA automatically recognises if the sourcefile is an executable,
  82.         an object file or any other (binary). It may happen that some
  83.         kind of binary data is recognised as an executable. To avoid this
  84.         make use of the -BINARY option.
  85.  
  86. -a      (off)
  87.         This option makes IRA append the address and data of an instruction
  88.         to every line. That is pretty useful to me. E.g. when code and data
  89.         is mixed, you can manually delete some instructions to replace them
  90.         by DC.x directives.
  91.  
  92. -i      (off)
  93.         Use this option to get some information about the hunk structure of
  94.         your sourcefile.
  95.  
  96. -OFFSET=<OFFSET> (-OFFSET=0)
  97.         When the sourcefile is relocated by IRA the offset value is added to
  98.         the relocation. Why should I do that ?
  99.         If you want to run an executable at a specific location in memory
  100.         you specify the address of that location with the -OFFSET option
  101.         in combination with the -KEEPBIN option. After running IRA you can
  102.         load the .BIN file to the specific location and execute it. You just
  103.         have to know what you're doing (e.g. contents of registers and so on).
  104.         The second, more useful application is to write a part of memory to a
  105.         file, then create a .ASM file with the -OFFSET option. You have to take
  106.         the address of the memory location as offset. E.g. you can create your
  107.         own kickfile with your own modifications (is it legal ?), of course
  108.         some additional work on the .ASM file has to be done.
  109.         OFFSET can be decimal or hexadecimal (e.g. -OFFSET=$4FF0).
  110.  
  111. -CACHE=x (-CACHE=10)
  112.         Before a WRITE command is executed the cache has to be filled with
  113.         data. That increases speed, especially on disk-based 68000 systems.
  114.         I never use this option so it might vanish with the next version of
  115.         IRA.
  116.  
  117. -TEXT=x (off)
  118.         There are two implemented methods of searching for text. So x can be
  119.         1 or 2. The text that is found is printed out to <stdout>. It may
  120.         happen that some stupid text lines show up, so you have to decide
  121.         individually about every line to include into the .ASM file.
  122.         Method 1 works better if code and data is mixed. Method 2 works
  123.         better if it is not mixed.
  124.  
  125. -KEEPZH (off)
  126.         There are files that have hunks with a length of zero. By default
  127.         these hunks don't appear in the .ASM file. If you want them to see
  128.         just use this option. There are executables where you have to use
  129.         this option because they work with there own SEGMENT structure.
  130.  
  131. -KEEPBIN (off)
  132.         Before the first pass an executable is relocated by IRA and written
  133.         to a .BIN file. Normally, this file is deleted at some point but if
  134.         you want to keep it for some purpose use the -KEEPBIN option.
  135.         E.g. for a <type >x.hex x.bin opt h>.
  136.  
  137. -OLDSTYLE (depends on the -M680x0 option)
  138.         This option forces IRA to use the old Motorola syntax like D16(PC)
  139.         instead of (D16,PC). By default this option is used for 68000 and
  140.         68010 processors.
  141.  
  142. -NEWSTYLE (depends on the -M680x0 option)
  143.         This option forces IRA to use the new Motorola syntax like (D16,PC)
  144.         instead of D16(PC). By default this option is used for 68020, 68030
  145.         and 68040 processors.
  146.  
  147. -SPLITFILE (off)
  148.         With this option the .ASM file is split up. Every section is put into
  149.         an own file. One 'main' file is created to include these files via
  150.         INCLUDE statements. What is it for ? I don't know. I was asked for
  151.         this option.
  152.  
  153. -BASEREG[=x,adr,sec]
  154.         You can use this option if the program uses the smalldata model. It
  155.         will provide you with a more readable .ASM file.
  156.         Smalldata model means the access to data is made by D16(An), and the
  157.         register An has to be preloaded by the SMALLDATABASE value. A lot of
  158.         compilers use A4 as baseregister and the address of the datasection
  159.         plus 32766 as the SMALLDATABASE.
  160.         A good way to find out if a program makes use of the smalldata model
  161.         is the following:
  162.         1. Type <IRA >x -a -i -basereg test>
  163.         2. Look at the file test.asm and x with an editor.
  164.            If there are memory accesses by D16(An) (e.g. move.l -32754(A4),D0)
  165.            look at the file x. There may be lines like BASEREG 00000008: A4.
  166.            The first number is the hexadecimal address of an instruction that
  167.            has A4 as destination register. Look at this address in the file
  168.            test.asm. You may find a line like LEA SECSTRT_1,A4. Perhabs, A4
  169.            is the baseregister and SECSTRT_1 the SMALLDATABASE. Now memo the
  170.            address of SECSTRT_1 (=adr).
  171.         3. Type <IRA -a -i -basereg=4,adr,1 test>
  172.         4. Look at test.asm and you will see LAB_xxxx instead of D16(A4).
  173.         5. The line NEAR A4,1 in test.asm tells the assembler to use the
  174.            smalldata model. This directive may differ from assembler to 
  175.            assembler.
  176.  
  177.         As always, be careful when modifying a program. Often code and data
  178.         is mixed or there are some program protection technics that makes it
  179.         hard to modify and run a program.
  180.  
  181.         
  182. HOW TO REASSEMBLE A PROGRAM
  183. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  184. First, you have to be sure that your Assembler, Linker and IRA work fine.
  185. That goes like follows:
  186.   (Let's assume the linker is called LN, the ASSEMBLER is called AS and the
  187.    program is called TEST.)
  188.  
  189.   1. Type <IRA -a TEST TEST1.S>
  190.   2. Type <AS -n TEST1.S>           (assume -n to be the NO_OPTIMISE flag)
  191.   3. Type <LN TEST1.O>
  192.   4. Type <IRA -a TEST1 TEST2.S>
  193.   5. Type <FDIFF TEST1.S TEST2.S RESYNC 1>
  194.  
  195. If no error pops up until now it's very likely that TEST1 will work. (Try it).
  196. If FDIFF tells you that there are differences between TEST1.S and TEST2.S you
  197. have to be careful with running TEST1 because there is at least one bug in
  198. IRA (I don't think so!) or in your assembler. Try to reproduce the error in
  199. a small file and tell me about it. I could provide an assembler buglist here.
  200.  
  201. If you got no problems with the five points above you can start with editing
  202. TEST1.S. First, try to find all data that is hidden in code sections and
  203. replace the instructions with DC.W directives. If you have done so try
  204. assembling TEST1.S with an optimising assembler (should work).
  205. To find parts of text use the -TEXT option. Or use the -KEEPBIN option and
  206. type <type >test.hex TEST.BIN opt h> and look at TEST.HEX for text.
  207.  
  208. To collect some experience it'll be better to begin with short programs.
  209.  
  210.  
  211. To reassemble bootblocks, disktracks or memory take a monitor program and these
  212. to a file. Then invoke IRA.
  213.  
  214.  
  215. WHAT ASSEMBLER CAN I USE ?
  216. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  217. You can use any assembler you want, but minor problems may occur:
  218.  
  219.   - There may be problems with the SECTION, MACHINE and NEAR directives.
  220.     Change these lines by hand or tell me the name and version of your
  221.     assembler and the syntax of the above directives. So I could build a
  222.     command-line option to switch between different assemblers.
  223.   - Some assemblers can't handle more than 2^16-1 (65535) lines. Get the
  224.     GigaPhxAss from Frank Wille (see below) for the big programs.
  225.   - If code and data is mixed in a code hunk you have to switch optimising
  226.     off when you run the assembler. Else the chance of having a damaged
  227.     program is very high. Some assemblers have problems with that. I call
  228.     that 'fodder for the garbage can'.
  229.  
  230. Tell me about any problems !!!
  231.  
  232. I use PHXASS from Frank Wille, a fast and excellent 680x0, FPU and MMU
  233. assembler. You can get it on AMINET somewhere.
  234. Or send a disk (with PD stuff, of course) and a self addressed envelope
  235. to:
  236.        Frank Wille
  237.        Auf dem Dreische 45
  238.        32049 Herford
  239.        GERMANY
  240.  
  241. Thanks a lot, Frank !
  242.  
  243.  
  244. CONDITIONS
  245. ¯¯¯¯¯¯¯¯¯¯
  246. IRA is shareware. The program may be freely distributed
  247. and copied, as long as the following conditions are
  248. fulfilled:
  249.  
  250. - The sales price must not be higher than the cost of
  251.   an (empty) disk plus a nominal copying fee plus
  252.   costs for shipping. The total price must not be higher
  253.   than 6 US$ or 10 DM.
  254. - All parts of the program and the documentation must
  255.   be complete. The distribution of single parts is not
  256.   allowed.
  257. - IRA or parts of it must not be sold in combination with
  258.   or as part of commercial software.
  259. - Program and documentation must not be changed in any way.
  260.   Exception is the use of archivers such as LHArc and packers
  261.   like "Imploder" or "Powerpacker", as long as it is possible
  262.   to retrieve the original program/data.
  263.  
  264.  
  265. I explicitly do not guarantee for the correct functioning of IRA.
  266. I explicitly reject any responsibility for any consequences from the use
  267. of IRA whatsoever. This includes, but is not limited to, secondary 
  268. consequences, personal injuries or other kinds of side effects.
  269.  
  270.  
  271.  
  272. I want to ask everybody, who uses IRA to send the amount of
  273.  
  274.      15 US$  or  20 DM
  275.  
  276. to the following address:
  277.  
  278.    Tim Ruehsen
  279.    Johannes-Rabe-Stieg 8
  280.    21033 Hamburg
  281.    Germany
  282.  
  283. Please send only cash.
  284.  
  285.  
  286.  
  287. ERROR REPORTS
  288. ¯¯¯¯¯¯¯¯¯¯¯¯¯
  289. If you find any errors, send me a disk with the program that causes trouble
  290. and tell me what command line you used. The disk will be returned with the
  291. newest version of IRA and some PD stuff.
  292. If you have questions or ideas about IRA send me a letter,
  293.  
  294. phone me (GERMANY 040-7216995) or
  295. EMAIL me (ruehsen@ifm.uni-hamburg.de).
  296.  
  297.  
  298.  
  299. HISTORY
  300. ¯¯¯¯¯¯¯
  301. V1.01    First released version.
  302.  
  303. V1.02
  304.        o CHIP and FAST hunks are now recognised.
  305.        o Addressing mode D8(PC,An) is now used with a label.
  306.        o Removed a never-ending-loop problem that came up with a special
  307.          program protection (a hack in the hunk structure).
  308.        o Removed the multiple-label problem.
  309.        o The MACHINE directive is no longer used in 68000 programs.
  310.        o Some of the command-line options changed.
  311.  
  312.  
  313. BETA-TESTERS
  314. ¯¯¯¯¯¯¯¯¯¯¯¯
  315. Thanks to all the testers of IRA (poor number):
  316.  
  317. Crisi, Torben, anonymous guy from Darmstadt and me, myself and I.
  318.  
  319.  
  320.  
  321.  
  322. Good Night, 'till next version.
  323.  
  324.  
  325.                      TIM RUEHSEN
  326.